Results

BindAI returns result objects from agent execution instead of exposing provider-specific response objects directly. The result gives applications a consistent way to access generated output and execution information.

AgentResult

Calling agent.run() returns an AgentResult.

result = agent.run("Explain what BindAI is.")

print(result.output)

AgentResult is the primary result type returned by BindAI agent execution. You can inspect the result during development:

print(result)

For the exact fields available in your installed BindAI version, inspect the result type directly:

from bindai import AgentResult
import inspect

print(inspect.signature(AgentResult))
print(AgentResult.__annotations__)

This is useful when working with a particular BindAI release because result details can evolve as the framework develops.

Accessing the Output

The generated response is available through result.output.

result = agent.run("What is BindAI?")

print(result.output)

For normal text generation, output contains the generated response. When structured output is requested, output contains the resulting Python object.

Checking Execution Status

AgentResult exposes a success status that can be used to determine whether the execution completed successfully.

result = agent.run("Hello!")

if result.success:
    print(result.output)
else:
    print(result.error)

This provides a simple application-level way to handle successful and unsuccessful results. Applications should still handle exceptions separately because not every failure necessarily produces an AgentResult.

Structured Output

BindAI supports structured output through the output parameter of run(). For example, a Pydantic model can define the expected result:

from pydantic import BaseModel

from bindai import Agent


class Person(BaseModel):
    name: str
    age: int


agent = (
    Agent.builder()
    .name("person-generator")
    .model("openai:gpt-4.1-mini")
    .instructions("Generate fictional people.")
    .build()
)

result = agent.run(
    "Generate a fictional person.",
    output=Person,
)

print(result.output)

When supported by the configured provider and model, the resulting output can be a validated Person instance rather than requiring manual JSON parsing. Provider and model capabilities should be verified when relying on structured output.

Inspecting Result Information

During development, inspect the result object directly:

result = agent.run("Hello!")

print(type(result))
print(result)
print(result.output)

If your application needs additional result metadata, inspect the installed AgentResult type:

from bindai import AgentResult

print(AgentResult.__annotations__)

This approach keeps application code aligned with the BindAI version being used.

Handling Execution Failures

Agent execution can fail for different reasons, including:

Provider configuration problems
Authentication failures
Invalid model configuration
Network failures
Tool execution failures
Provider service errors
Other execution errors

Applications should not assume that every failure is represented by a particular AgentResult field. For operations that can raise exceptions, handle them explicitly:

try:
    result = agent.run("Hello!")
    print(result.output)
except Exception as exc:
    print(f"Agent execution failed: {exc}")

When an operation returns an AgentResult, the application can inspect its status:

result = agent.run("Hello!")

if result.success:
    print(result.output)
else:
    print(result.error)

For production applications, catch specific exception types when the application needs to distinguish between different failure categories.

Results and Exceptions

Result objects and Python exceptions serve different purposes. A result represents an operation that completed and returned an AgentResult. An exception represents a failure that interrupts normal execution. For example:

try:
    result = agent.run("Hello!")
except Exception as exc:
    print(f"Execution failed: {exc}")
else:
    if result.success:
        print(result.output)
    else:
        print(result.error)

This distinction is important when building production applications. Do not assume that every possible provider or execution failure will be converted into an AgentResult.

Tool Results

Tool results are separate from AgentResult. A tool can return ordinary Python values:

from bindai import tool


@tool
def add(a: int, b: int):
    return a + b

The returned value becomes part of the tool execution flow when the agent invokes the tool. Conceptually:

Agent
  |
  v
Model
  |
  v
Tool
  |
  v
Tool Result
  |
  v
Agent Execution
  |
  v
AgentResult

Tool results should therefore not be treated as identical to the final AgentResult. For advanced tool execution and result handling, use the BindAI Tool API.

Workflow Results

Workflows have their own execution model and result handling. A workflow can produce values that are passed between workflow nodes and eventually exposed as workflow output. For example:

result = workflow.run()

print(result)

The exact workflow result structure depends on the workflow implementation. When working with workflow results programmatically, inspect the returned object:

print(type(result))
print(result)

Do not assume that every workflow result has the same fields as AgentResult.

Result Flow

The general agent execution model can be represented as:

Agent Execution
      |
      v
  AgentResult
      |
      +---- output
      |
      +---- success
      |
      +---- error
      |
      +---- additional execution information

The exact information available on the result depends on the BindAI version and execution path. The primary application-facing values are the execution status and generated output.

Results and Structured Applications

Structured results are particularly useful when agent output is consumed by application code. For example:

from pydantic import BaseModel

from bindai import Agent


class Task(BaseModel):
    title: str
    priority: int


agent = (
    Agent.builder()
    .name("task-generator")
    .model("openai:gpt-4.1-mini")
    .instructions("Generate structured tasks.")
    .build()
)

result = agent.run(
    "Create a task for reviewing documentation.",
    output=Task,
)

if result.success:
    task = result.output
    print(task.title)
    print(task.priority)
else:
    print(result.error)

This allows downstream application code to work with a defined Python type instead of manually parsing generated text.

Results from Streaming

Streaming execution differs from standard run() execution. For example:

for chunk in agent.stream_chat("Explain neural networks."):
    print(chunk)

Streaming produces incremental output rather than waiting for a complete AgentResult before displaying the response. Use standard run() when the application needs the completed execution result. Use streaming when the application needs to process or display output progressively.

Debugging Results

During development, inspect the complete result and its type:

result = agent.run("Explain dependency injection.")

print(type(result))
print(result)
print(result.output)

You can also inspect the result class:

from bindai import AgentResult

print(AgentResult.__annotations__)

This is particularly useful when developing against a changing or locally installed version of BindAI.

Keeping Provider Responses Out of Application Code

One purpose of AgentResult is to prevent application code from depending directly on provider SDK response objects. Instead of writing provider-specific response handling:

Application
    |
    +---- OpenAI response
    |
    +---- Anthropic response
    |
    +---- Gemini response

BindAI provides a common application-facing result abstraction:

Application
    |
    v
Agent
    |
    v
Provider
    |
    v
AgentResult

This allows the underlying provider to change while keeping the application’s agent execution interface consistent. Provider-specific capabilities can still affect the execution behavior and available features.

Result Handling in Applications

A typical application can handle an agent result like this:

result = agent.run("Explain what BindAI is.")

if result.success:
    print("Agent response:")
    print(result.output)
else:
    print("Agent execution failed:")
    print(result.error)

This pattern keeps result handling simple and independent from the provider implementation.

Result Handling Best Practices

Use result.output to access generated agent output.
Check result.success when application behavior depends on successful execution.
Use structured output when downstream code requires predictable Python objects.
Inspect result types instead of assuming undocumented fields.
Handle execution exceptions explicitly when failures need special treatment.
Keep provider-specific response handling out of application code.
Treat tool results separately from final agent results.
Treat workflow results according to the workflow API rather than assuming they match AgentResult.
Test result handling against the BindAI version used by the application.
Verify provider support when relying on structured output or streaming.

Summary

AgentResult is the primary result abstraction returned by BindAI agent execution. For standard text generation, access the generated response through result.output. Use result.success and result.error when the application needs to handle unsuccessful results. For structured generation, output can contain a validated Python object when supported by the configured provider and model. Exceptions should be handled separately because not every execution failure necessarily produces an AgentResult. By relying on the BindAI result abstraction rather than provider-specific response objects, applications can remain more portable across providers and models.

Getting Started

Core

Tools

Memory

Knowledge

Connections

Automation

Workflows

Projects

Templates

Roadmap

API Reference

02.5 results

Results

AgentResult

Accessing the Output

Checking Execution Status

Structured Output

Inspecting Result Information

Handling Execution Failures

Results and Exceptions

Tool Results

Workflow Results

Result Flow

Results and Structured Applications

Results from Streaming

Debugging Results

Keeping Provider Responses Out of Application Code

Result Handling in Applications

Result Handling Best Practices

Summary

​Results

​AgentResult

​Accessing the Output

​Checking Execution Status

​Structured Output

​Inspecting Result Information

​Handling Execution Failures

​Results and Exceptions

​Tool Results

​Workflow Results

​Result Flow

​Results and Structured Applications

​Results from Streaming

​Debugging Results

​Keeping Provider Responses Out of Application Code

​Result Handling in Applications

​Result Handling Best Practices

​Summary

Results

AgentResult

Accessing the Output

Checking Execution Status

Structured Output

Inspecting Result Information

Handling Execution Failures

Results and Exceptions

Tool Results

Workflow Results

Result Flow

Results and Structured Applications

Results from Streaming

Debugging Results

Keeping Provider Responses Out of Application Code

Result Handling in Applications

Result Handling Best Practices

Summary